<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>Using Layout Managers</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 5.1.2 Build 015" />
<meta name="date" content="2011-11-03T11:27:21Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Using Layout Managers" />
<meta name="relnum" content="Release 1.5" />
<meta name="partnum" content="E23376-02" />
<link rel="copyright" href="./dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="stylesheet" href="./dcommon/css/blafdoc.css" title="Oracle BLAFDoc" type="text/css" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="index" href="index.htm" title="Index" type="text/html" />
<link rel="prev" href="dialogs.htm" title="Previous" type="text/html" />
<link rel="next" href="style.htm" title="Next" type="text/html" />
</head>
<body>
<div class="header"><a id="top" name="top"></a>
<div class="zz-skip-header"><a href="#BEGIN">Skip Headers</a></div>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><b>Lightweight UI Toolkit Developer's Guide</b><br />
<b>Release 1.5</b><br />
E23376-02</td>
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="./dcommon/gifs/toc.gif" alt="Go To Table Of Contents" /><br />
<span class="icon">Contents</span></a></td>
<td align="center" valign="top"><a href="index.htm"><img src="./dcommon/gifs/index.gif" alt="Go To Index" /><br />
<span class="icon">Index</span></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100">
<tr>
<td align="center"><a href="dialogs.htm"><img src="./dcommon/gifs/leftnav.gif" alt="Previous" /><br />
<span class="icon">Previous</span></a>&nbsp;</td>
<td align="center"><a href="style.htm"><img src="./dcommon/gifs/rightnav.gif" alt="Next" /><br />
<span class="icon">Next</span></a></td>
<td>&nbsp;</td>
</tr>
</table>
<a name="BEGIN" id="BEGIN"></a></div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="BBJEHCEA" name="BBJEHCEA"></a>
<h1 class="chapter"><span class="secnum">6</span> Using Layout Managers</h1>
<p>This chapter shows you how to use the layout managers provided by the Lightweight UI Toolkit library. It also gives an example of writing a custom layout manager. For each layout manager, this chapter supplies sample code demonstrating how to use the layout manager and a general illustration.</p>
<p>In Lightweight UI Toolkit you can find the following layout managers:</p>
<ul>
<li>
<p><a href="#BBJDIDGG">BorderLayout</a></p>
</li>
<li>
<p><a href="#BBJFGBBH">BoxLayout</a></p>
</li>
<li>
<p><a href="#BBJHEIBE">FlowLayout</a></p>
</li>
<li>
<p><a href="#BBJHBJBI">GridLayout</a></p>
</li>
<li>
<p><a href="#BBJEHJJG">GroupLayout</a></p>
</li>
<li>
<p><a href="#BBJFEEFB">Coordinate Layout</a></p>
</li>
<li>
<p><a href="#BBJBJCBD">Table Layout</a></p>
</li>
</ul>
<a id="BBJDIDGG" name="BBJDIDGG"></a>
<div class="sect1">
<h2 class="sect1">BorderLayout</h2>
<p>A <a id="sthref101" name="sthref101"></a>BorderLayout object has five areas. These areas are specified by the BorderLayout constants:</p>
<ul>
<li>
<p>Center</p>
</li>
<li>
<p>East</p>
</li>
<li>
<p>North</p>
</li>
<li>
<p>South</p>
</li>
<li>
<p>West</p>
</li>
</ul>
<p>When adding a component to a container, specify the component's location (for example, <code>BorderLayout.CENTER</code>) as one of the arguments to the addComponent method. If this component is missing from a container, controlled by a BorderLayout object, make sure that the component's location was specified and that no other component was placed in the same location. <a id="sthref102" name="sthref102"></a></p>
<p><code>addComponent(BorderLayout.CENTER, component) // preferred</code></p>
<p>or</p>
<p><code>addComponent(&ldquo;Center&rdquo;, component) // valid but error prone</code></p>
<p>The center area gets as much of the available space as possible. The other areas expand only as much as necessary to fit the components that have been added to it. Often a container uses only one or two of the areas of the BorderLayout object &mdash; just the center, or the center and the bottom.</p>
<div class="figure"><a id="Z40006f11290807" name="Z40006f11290807"></a>
<p class="titleinfigure">Figure 6-1 BorderLayoutLocations</p>
<img src="img/border_layout.jpg" alt="Description of Figure 6-1 follows" title="Description of Figure 6-1 follows" longdesc="img_text/border_layout.htm" /><br />
<a id="sthref103" name="sthref103" href="img_text/border_layout.htm">Description of "Figure 6-1 BorderLayoutLocations"</a><br />
<br /></div>
<!-- class="figure" --></div>
<!-- class="sect1" -->
<a id="BBJFGBBH" name="BBJFGBBH"></a>
<div class="sect1">
<h2 class="sect1">BoxLayout</h2>
<p>The <a id="sthref104" name="sthref104"></a>BoxLayout class puts components either on top of each other or in a row &ndash; your choice.</p>
<a id="Z40008821290575" name="Z40008821290575"></a>
<div class="sect2">
<h3 class="sect2">X_AXIS</h3>
<p>To lay out components in a row, use <code>BoxLayout.X_AXIS</code> as the axis indication.</p>
<p><code>BoxLayout boxLayout = new BoxLayout(BoxLayout.X_AXIS);</code></p>
<p>In this layout, the box layout manager honors the component width of each layout component to fill the width of the container, and the height is determined by the container height. Any extra space appears at the right side of the container, as shown in <a href="#Z40006f11290845">Figure 6-2</a>.</p>
<div class="figure"><a id="Z40006f11290845" name="Z40006f11290845"></a>
<p class="titleinfigure">Figure 6-2 BoxLayout.X_AXIS Components in a Row</p>
<img src="img/boxlayout_x.jpg" alt="Description of Figure 6-2 follows" title="Description of Figure 6-2 follows" longdesc="img_text/boxlayout_x.htm" /><br />
<a id="sthref105" name="sthref105" href="img_text/boxlayout_x.htm">Description of "Figure 6-2 BoxLayout.X_AXIS Components in a Row"</a><br />
<br /></div>
<!-- class="figure" --></div>
<!-- class="sect2" -->
<a id="Z40008821290584" name="Z40008821290584"></a>
<div class="sect2">
<h3 class="sect2">Y_AXIS</h3>
<p>To lay out components in a column, use <code>BoxLayout.Y_AXIS</code> as the axis indication.</p>
<p><code>BoxLayout boxLayout = new BoxLayout(BoxLayout.Y_AXIS);</code></p>
<p>In this layout, the box layout manager honors the component height of each layout component to fill the height of the container, and the width is determined by the container width. Any extra space appears at the bottom of the container, as shown in <a href="#Z40006f11290895">Figure 6-3</a>.</p>
<div class="figure"><a id="Z40006f11290895" name="Z40006f11290895"></a>
<p class="titleinfigure">Figure 6-3 BoxLayout_Y_Axis Components in a Row</p>
<img src="img/boxlayout_y.jpg" alt="Description of Figure 6-3 follows" title="Description of Figure 6-3 follows" longdesc="img_text/boxlayout_y.htm" /><br />
<a id="sthref106" name="sthref106" href="img_text/boxlayout_y.htm">Description of "Figure 6-3 BoxLayout_Y_Axis Components in a Row"</a><br />
<br /></div>
<!-- class="figure" --></div>
<!-- class="sect2" --></div>
<!-- class="sect1" -->
<a id="BBJHEIBE" name="BBJHEIBE"></a>
<div class="sect1">
<h2 class="sect1">FlowLayout</h2>
<p>The <a id="sthref107" name="sthref107"></a>FlowLayout class provides a very simple layout manager that is the default layout manager for Container objects.</p>
<p>The FlowLayout class puts components in a row, sized at their preferred size. If the horizontal space in the container is too small to put all the components in one row, the FlowLayout class uses multiple rows. To align the row to the left, right, or center, use a FlowLayout constructor that takes an alignment argument.</p>
<p>The code snippet below creates a FlowLayout object and the components it manages.</p>
<pre xml:space="preserve" class="oac_no_warn">
FlowLayout exampleLayout = new FlowLayout();
 
...
 
container.setLayout(exampleLayout);
 
container.addComponent(new Button("Button 1"));
container.addComponent(new Button("Button 2"));
container.addComponent(new Button("Button 3"));
container.addComponent(new Button("Button 4"));
</pre>
<div class="figure"><a id="Z40006f11290949" name="Z40006f11290949"></a>
<p class="titleinfigure">Figure 6-4 FlowLayout Default Alignment</p>
<img src="img/flow_layout_right.jpg" alt="Description of Figure 6-4 follows" title="Description of Figure 6-4 follows" longdesc="img_text/flow_layout_right.htm" /><br />
<a id="sthref108" name="sthref108" href="img_text/flow_layout_right.htm">Description of "Figure 6-4 FlowLayout Default Alignment"</a><br />
<br /></div>
<!-- class="figure" -->
<p>When constructing a FlowLayout manager you can select either the Left, Right, or Center option to set up the component's orientation. The default alignment is Left. The following code snippet applies the Right component orientation to the above exampleLayout.</p>
<p><code>FlowLayout exampleLayout = new FlowLayout(Component.RIGHT);</code></p>
<div class="figure"><a id="Z40006f11290990" name="Z40006f11290990"></a>
<p class="titleinfigure">Figure 6-5 FlowLayout With Right Alignment</p>
<img src="img/flow_layout_right.jpg" alt="Description of Figure 6-5 follows" title="Description of Figure 6-5 follows" longdesc="img_text/flow_layout_right.htm" /><br />
<a id="sthref109" name="sthref109" href="img_text/flow_layout_right.htm">Description of "Figure 6-5 FlowLayout With Right Alignment"</a><br />
<br /></div>
<!-- class="figure" --></div>
<!-- class="sect1" -->
<a id="BBJHBJBI" name="BBJHBJBI"></a>
<div class="sect1">
<h2 class="sect1">GridLayout</h2>
<p>A <a id="sthref110" name="sthref110"></a>GridLayout object places components in a grid of cells. Each component takes all the available space within its cell, and each cell is exactly the same size.</p>
<p>The code snippet below creates the GridLayout object and the components it manages.</p>
<pre xml:space="preserve" class="oac_no_warn">
GridLayout exampleLayout = new GridLayout(0,2);
 
...
container.setLayout(exampleLayout);
 
container.addComponent(new Button("Button 1"));
container.addComponent(new Button("Button 2"));
container.addComponent(new Button("Button 3"));
container.addComponent(new Button("Button 4"));
</pre>
<p>In this example the constructor of the GridLayout class creates an instance that has two columns and as many rows as necessary.</p>
<div class="figure"><a id="Z40006f11291038" name="Z40006f11291038"></a>
<p class="titleinfigure">Figure 6-6 GridLayout With Two Columns</p>
<img src="img/grid_layout.jpg" alt="Description of Figure 6-6 follows" title="Description of Figure 6-6 follows" longdesc="img_text/grid_layout.htm" /><br />
<a id="sthref111" name="sthref111" href="img_text/grid_layout.htm">Description of "Figure 6-6 GridLayout With Two Columns"</a><br />
<br /></div>
<!-- class="figure" --></div>
<!-- class="sect1" -->
<a id="BBJEHJJG" name="BBJEHJJG"></a>
<div class="sect1">
<h2 class="sect1">GroupLayout</h2>
<p><a id="sthref112" name="sthref112"></a>GroupLayout is a layout manager that was developed for GUI builders such as Matisse, the Java SE GUI builder delivered with the NetBeans IDE. Although the layout manager was originally designed to suit GUI builder needs, it also works well for manual coding. To get more information you can refer to the GroupLayout API (http://java.sun.com/javase/6/docs/api/javax/swing/GroupLayout.html (<code><a href="http://java.sun.com/javase/6/docs/api/javax/swing/GroupLayout.html">http://java.sun.com/javase/6/docs/api/javax/swing/GroupLayout.html</a></code>)) or review the Swing GroupLayout tutorial at:</p>
<p>http://java.sun.com/docs/books/tutorial/uiswing/layout/group.html (<code><a href="http://java.sun.com/docs/books/tutorial/uiswing/layout/group.html">http://java.sun.com/docs/books/tutorial/uiswing/layout/group.html</a></code>)</p>
</div>
<!-- class="sect1" -->
<a id="BBJFEEFB" name="BBJFEEFB"></a>
<div class="sect1">
<h2 class="sect1">Coordinate Layout</h2>
<p>Unlike other <a id="sthref113" name="sthref113"></a>layout managers coordinate layout assigns a component an absolute position in relation to the space available within the UI. The coordinate layout allows developers to position components within an X/Y location, however, it doesn't guarantee the position won't change and doesn't determine absolute positions.</p>
<p>Instead coordinate layout accepts positions as "relative" and calculates the actual position based on available space. This is essential since the available size for a container might change at runtime based on font size, screen rotation, etcetera.</p>
<p>For example, a coordinate layout for 200x200 will show a 20x20 component placed in the 90x90 position exactly in the center, regardless of the actual size of the container. If the container is laid out to a larger size, for example, 190x300 the component in the center would still be centered.</p>
<p>Unlike the other standard layouts in LWUIT the coordinate layout allows positioning components on top of one another to achieve z-ordering. The z-ordering is determined by the order in which the components are placed into the parent container.The last component added is the one on top.</p>
<pre xml:space="preserve" class="oac_no_warn">
Display.init(this);
final Form mainForm = new Form("Coordinate Layout");
mainForm.setLayout(new CoordinateLayout(200, 200));
 
Label centeredLabel = new Label("Center");
centeredLabel.setX(90);
centeredLabel.setY(90);
centeredLabel.getUnselectedStyle().setBgTransparency(100);
centeredLabel.getUnselectedStyle().setBgColor(0xff);
 
Label underCenter = new Label("Under Center");
underCenter.setX(80);
underCenter.setY(95);
 
Label top = new Label("Top Left");
top.setAlignment(Component.CENTER);
top.setX(0);
top.setY(0);
top.setPreferredW(200);
top.setPreferredH(30);
top.getUnselectedStyle().setBgColor(0xff0000);
 
mainForm.addComponent(underCenter);
mainForm.addComponent(centeredLabel);
mainForm.addComponent(top);
 
mainForm.show();
</pre>
<p>This code produces <a href="#Z4000fd31292294">Figure 6-7</a>:</p>
<div class="figure"><a id="Z4000fd31292294" name="Z4000fd31292294"></a>
<p class="titleinfigure">Figure 6-7 Coordinate Layout Sample</p>
<img src="img/coordinatelayout.jpg" alt="Description of Figure 6-7 follows" title="Description of Figure 6-7 follows" longdesc="img_text/coordinatelayout.htm" /><br />
<a id="sthref114" name="sthref114" href="img_text/coordinatelayout.htm">Description of "Figure 6-7 Coordinate Layout Sample"</a><br />
<br /></div>
<!-- class="figure" -->
<p>There are several interesting things we can glean even from this simple example:</p>
<ul>
<li>
<p>Coordinate layout must be hard-coded. The coordinates are implicitly scaled by LWUIT so there is no need to use logic, such as <code>getWidth/Height,</code> to calculate positions.</p>
</li>
<li>
<p>Elements are sized based on their preferred size, yet positioned based on their X and Y coordinates. Their dimensions determined via <code>setWidth</code> and <code>getHeight</code> are ignored.</p>
</li>
<li>
<p>Unlike the X and Y coordinates that are relative to layout dimensions, the preferred size is absolute in pixels and should be calculated based on content dimensions. This works as expected as long as you don't change the preferred size on your own.</p>
</li>
<li>
<p>Alignment and other LWUIT related positioning logic should work as you would expect.</p>
</li>
</ul>
</div>
<!-- class="sect1" -->
<a id="BBJBJCBD" name="BBJBJCBD"></a>
<div class="sect1">
<h2 class="sect1">Table Layout</h2>
<p>The <a id="sthref115" name="sthref115"></a>table layout is a part of the table component discussed later, however it is quite useful on its own. It is largely inspired by the HTML table tag and also influenced by AWT's GridBagLayout.</p>
<p>The table layout is a constraint based layout (similar to the border layout). Other layout managers expect components to be added on their own. For example:</p>
<p><code>container.addComponent(component);</code></p>
<p>The table layout container expects something like this:</p>
<p><code>container.addComponent(tableConstraint, component);</code></p>
<p>Notice that this syntax is optional. If the constraint is omitted, the component is placed in the next available cell.</p>
<p>The table layout will automatically size components to the largest preferred size in the row or column until you run out of space. If the table is not horizontally scrollable this happens when the edge of the parent container is reached (near the edge of the screen), and additional components are "crammed together". Notice that all cells in the table layout are always sized to fit the entire cell. To change a cell's alignment or margin, use the Component or Style methods.</p>
<p>The constraint argument is an instance of TableLayout.Constraint that can be used only once. Reusing the instance will cause an exception.</p>
<p>A constraint can specify the absolute row/column where the entry should fit as well as spanning between cell boundaries.</p>
<div class="figure"><a id="Z40002551292121" name="Z40002551292121"></a>
<p class="titleinfigure">Figure 6-8 Table Layout Sample</p>
<img src="img/tablelayout.jpg" alt="Description of Figure 6-8 follows" title="Description of Figure 6-8 follows" longdesc="img_text/tablelayout.htm" /><br />
<a id="sthref116" name="sthref116" href="img_text/tablelayout.htm">Description of "Figure 6-8 Table Layout Sample"</a><br />
<br /></div>
<!-- class="figure" -->
<p>In <a href="#Z40002551292121">Figure 6-8</a>, the "First" cell is spanned vertically while the "Spanning" cell is spanned horizontally. This is immensely useful in creating elaborate UIs.</p>
<p>Constraints can also specify a height/width for a column/row that will override the default. This size is indicated in percentage of the total table layout size. In the code below you can see that the "First" label is sized to 50% width while the "Fourth" label is sized to 20% height.</p>
<pre xml:space="preserve" class="oac_no_warn">
final Form mainForm = new Form("Table Layout");
TableLayout layout = new TableLayout(4, 3);
mainForm.setLayout(layout);
TableLayout.Constraint constraint = layout.createConstraint();
constraint.setVerticalSpan(2);
constraint.setWidthPercentage(50);
mainForm.addComponent(constraint, new Label("First"));
mainForm.addComponent(new Label("Second"));
mainForm.addComponent(new Label("Third"));
 
constraint = layout.createConstraint();
constraint.setHeightPercentage(20);
mainForm.addComponent(constraint, new Label("Fourth"));
mainForm.addComponent(new Label("Fifth"));
constraint = layout.createConstraint();
constraint.setHorizontalSpan(3);
Label span = new Label("Spanning");
span.getStyle().setBorder(Border.createLineBorder(2));
span.setAlignment(Component.CENTER);
mainForm.addComponent(constraint, span);
mainForm.show();
</pre></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="dialogs.htm"><img src="./dcommon/gifs/leftnav.gif" alt="Previous" /><br />
<span class="icon">Previous</span></a>&nbsp;</td>
<td align="center"><a href="style.htm"><img src="./dcommon/gifs/rightnav.gif" alt="Next" /><br />
<span class="icon">Next</span></a></td>
</tr>
</table>
</td>
<td class="copyrightlogo"><img class="copyrightlogo" src="./dcommon/gifs/oracle.gif" alt="Oracle Logo" /><br />
<span class="copyrightlogo">Copyright&nbsp;&copy;&nbsp;2008, 2011,&nbsp;Oracle&nbsp;and/or&nbsp;its&nbsp;affiliates.&nbsp;All&nbsp;rights&nbsp;reserved.</span> <a href="./dcommon/html/cpyr.htm"><br />
<span class="copyrightlogo">Legal Notices</span></a></td>
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="./dcommon/gifs/toc.gif" alt="Go To Table Of Contents" /><br />
<span class="icon">Contents</span></a></td>
<td align="center" valign="top"><a href="index.htm"><img src="./dcommon/gifs/index.gif" alt="Go To Index" /><br />
<span class="icon">Index</span></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
</body>
</html>
